<?php

/**
 * Xml writer class to make writing xml more convenient, using push and pop Interface
 * @category Ebay
 * @package Ebay_XmlWriter
 * @author Luke Parry
*/
class Ebay_XmlWriter extends XMLWriter
{
    /**
	 * Creates a new XmlWriter document
	 * @param boolean $document whether a document tag should be created
	 * return Ebay_XmlWriter
	 */
    public function create($document = false)
    {
        $this->openMemory();
        if($document) $this->startDocument("1.0", 'utf-8');
        return $this;
    }
	
	
    /**
	 * Pushs or opens a new xml element, does not close the element
	 * Idea for push and pop inspired by @link http://simonwillison.net/2003/Apr/29/xmlWriter/
	 * @param string|array $name the name of the element
	 * @param mixed $text textual contents for the element
	 * @param array $attributes optional attributes for the element
	 * @return Ebay_XmlWriter
	 */
    public function push($name, $text = null, $attributes = array())
    {
        if(is_array($name))
        {
            if(isset($element['elements'])) //This is just one
            {
                foreach($elements['elements'] as $element)
                {
                        $this->push($element);
                        $this->pop();
                }
                $this->pop();
            }
            else
            {
                $this->push($element['name'], $element['text'], $element['attributes']);
            }
        }
        else
        {
            $this->startElement($name);

            foreach($attributes as $attribute => $value)
            {
                $this->writeAttribute($attribute, $value);
            }
            if(isset($text))
            {
                $this->text($text);
            }
            return $this;
        }
    }
	
	
	/**
	 * An iterative function that pushes many XML elements from a given array
	 * @param array $elements the array of elements to push
	 * @return Ebay_XmlWriter
	 */
	public function pushElements($elements)
	{
		foreach($elements as $name => $value)
		{
			
			if(is_array($value) || is_object($value))
			{
				$this->push($name);
				$this->pushElements($value);
			}
			else
			{
				$this->push($name, $value);
			}
			$this->pop();
		}
		return $this;
	}
	
	
	/**
	 * Closes an open XML element
	 * @param integer $num an optional number of elements that should be closed
	 * @return Ebay_XmlWriter
	 */
    public function pop($num = null)
    {
        if(isset($num))
        {
            for($i = $num; $i > 0; $i--)
            {
                $this->pop();
            }
        }
        else
        {
            $this->endElement();
        }
        return $this;
    }

	
	/**
	 * End the document
	 * @return Ebay_XmlWriter
	 */
    public function end()
    {
        $this->endDocument();
        return $this;
    }
	
	
	/**
	 * Flush the XML contents stored in the memory
	 * @return Ebay_XmlWriter
	 */
    public function delete() //Flush the buffer completly
    {
        $this->flush(true);
        return $this;
    }

	
	/**
	 * Magic method that converts the stored contents in the memory to a string
	 * @return string
	 */
    public function __toString()
    {
        return $this->flush(false); //Simply return the xml currently stored in the buffer without deleting it
    }
}